CTextDocument2 Class

Class that wraps all the methods of the ITextDocument and ITextDocument2 interfaces.

Name Description
CONSTRUCTORS Called when a class variable is created.
DESTRUCTOR Called automatically when a class variable goes out of scope or is destroyed.
LET Assignment operator.
CAST Cast operator.
TextDocumentPtr Returns a pointer to the underlying ITextDocument2 interface.
Attach Attaches an ITextDocument2 interface pointer to the class.
Detach Detaches the underlying ITextDocument2 interface pointer from the class.

ITextDocument Interface

The ITextDocument interface is the Text Object Model (TOM) top-level interface, which retrieves the active selection and range objects for any story in the document—whether active or not. It enables the application to:

When to implement

Applications typically do not implement the ITextDocument interface. Microsoft text solutions, such as rich edit controls, implement ITextDocument as part of their TOM implementation.

When to Use

Applications can retrieve an ITextDocument pointer from a rich edit control. To do this, send an EM_GETOLEINTERFACE message to retrieve an IRichEditOle object from a rich edit control. Then, call the object’s IUnknown::QueryInterface method to retrieve an ITextDocument pointer.

Inheritance

The ITextDocument interface inherits from the IDispatch interface. ITextDocument also has these types of members:

Name Description
GetName Gets the file name of this document.
GetSelection Gets the active selection.
GetStoryCount Gets the count of stories in this document.
GetStoryRanges Gets the story collection object used to enumerate the stories in a document.
GetSaved Gets a value that indicates whether changes have been made since the file was last saved.
SetSaved Sets the document Saved property.
GetDefaultTabStop Gets the default tab width.
SetDefaultTabStop Sets the default tab stop, which is used when no tab exists beyond the current display position.
New_ Opens a new document.
Open Opens a specified document. There are parameters to specify access and sharing privileges, creation and conversion of the file, as well as the code page for the file.
Save Saves the document.
Freeze Increments the freeze count.
Unfreeze Decrements the freeze count.
BeginEditCollection Turns on edit collection (also called undo grouping).
EndEditCollection Turns off edit collection (also called undo grouping).
Undo Performs a specified number of undo operations.
Redo Performs a specified number of redo operations.
Range Retrieves a text range object for a specified range of content in the active story of the document.
RangeFromPoint Retrieves a range for the content at or nearest to the specified point on the screen.

ITextDocument2 Interface

Extends the ITextDocument interface, adding methods that enable the Input Method Editor (IME) to drive the rich edit control, and methods to retrieve other interfaces such as ITextDisplays, ITextRange2, ITextFont2, ITextPara2, and so on.

Some ITextDocument2 methods used with the IME need access to the current window handle (HWND). Use the GetWindow method of the ITextDocument2 interface to retrieve the handle.

Name Description
GetCaretType Gets the caret type.
SetCaretType Sets the caret type.
GetDisplays Gets the displays collection for this Text Object Model (TOM) engine instance.
GetDocumentFont Gets an object that provides the default character format information for this instance of the Text Object Model (TOM) engine.
SetDocumentFont Sets the default paragraph formatting for this instance of the Text Object Model (TOM) engine.
GetDocumentPara Gets an object that provides the default paragraph format information for this instance of the Text Object Model (TOM) engine.
SetDocumentPara Sets the default paragraph formatting for this instance of the Text Object Model (TOM) engine.
GetEastAsianFlags Gets the East Asian flags.
GetGenerator Gets the name of the Text Object Model (TOM) engine.
SetIMEInProgress Sets the state of the Input Method Editor (IME) in-progress flag.
GetNotificationMode Gets the notification mode.
SetNotificationMode Sets the notification mode. Use tomTrue to turn on notifications, or tomFalse to turn them off.
GetSelection2 Gets the active selection.
GetStoryRanges2 Gets an object for enumerating the stories in a document.
GetTypographyOptions Gets the typography options.
GetVersion Gets the version number of the Text Object Model (TOM) engine.
GetWindow Gets the handle of the window that the Text Object Model (TOM) engine is using to display output.
AttachMsgFilter Attaches a new message filter to the edit instance. All window messages that the edit instance receives are forwarded to the message filter.
CheckTextLimit Checks whether the number of characters to be added would exceed the maximum text limit.
GetCallManager Gets the call manager.
GetClientRect Retrieves the client rectangle of the rich edit control.
GetEffectColor Retrieves the color used for special text attributes.
GetImmContext Gets the Input Method Manager (IMM) input context from the Text Object Model (TOM) host.
GetPreferredFont Retrieves the preferred font for a particular character repertoire and character position.
GetProperty Retrieves the value of a property.
GetStrings Gets a collection of rich-text strings.
Notify Notifies the Text Object Model (TOM) engine client of particular Input Method Editor (IME) events.
Range2 Retrieves a new text range for the active story of the document.
RangeFromPoint2 Retrieves the degenerate range at (or nearest to) a particular point on the screen.
ReleaseCallManager Releases the call manager.
ReleaseImmContext Releases an Input Method Manager (IMM) input context.
SetEffectColor Specifies the color to use for special text attributes.
SetProperty Specifies a new value for a property.
SetTypographyOptions Specifies the typography options for the document.
SysBeep Generates a system beep.
Update Updates the selection and caret.
UpdateWindow Notifies the client that the view has changed and the client should update the view if the Text Object Model (TOM) engine is in-place active.
GetMathProperties Gets the math properties for the document.
SetMathProperties Specifies the math properties to use for the document.
GetActiveStory Gets the active story; that is, the story that receives keyboard and mouse input.
SetActiveStory Sets the active story; that is, the story that receives keyboard and mouse input.
GetMainStory Gets the main story.
GetNewStory Gets a new story. Not implemented.
GetStory Retrieves the story that corresponds to a particular index.

Methods inherited from CTextObjectBase Class

Name Description
GetLastResult Returns the last result code
SetResult Sets the last result code.
GetErrorInfo Returns a description of the last result code.

CONSTRUCTORS

Called when a CTextDocument2 class variable is created.

DECLARE CONSTRUCTOR
DECLARE CONSTRUCTOR (BYVAL hRichEdit AS HWND)
DECLARE CONSTRUCTOR (BYVAL pTextDocument2 AS ITextDocument2 PTR, BYVAL fAddRef AS BOOLEAN = FALSE)

CONSTRUCTOR (Empty)

Can be used, for example, when we have an ITextDocument2 interface pointer returned by a function and we want to attach it to a new instance of the CTextDocument2 class.

DIM pCTextDocument2 AS CTextDocument2
pCTextDocument2.Attach(pTextDocument2)

CONSTRUCTOR (hRichEdit)

Parameter Description
hRichEdit Handle of the Rich Edit control. 
CONSTRUCTOR CTextDocument2 (BYVAL hRichEdit AS HWND)

CONSTRUCTOR (ITextDocument2 PTR)

CONSTRUCTOR CTextDocument2 (BYVAL pTextDocument2 AS ITextDocument2 PTR, BYVAL fAddRef AS BOOLEAN = FALSE)
Parameter Description
pTextDocument2 An ITextDocument2 interface pointer.
fAddRef Optional. TRUE to increment the reference count of the passed ITextDocument2 interface pointer; otherwise, FALSE. Default is FALSE.

Return value

A pointer to the new instance of the class.

Usage examples

To use with the dotted syntax.

SCOPE
   ' // Create a new instance of the CTextDocument2 class
   DIM pTextDocument2 AS CTextDocument2 = hRichEdit
   ' // Get the number of characters of the text in the Rich Edit control
   DIM numChars AS LONG = RichEdit_GetTextLength(hRichEdit)
   ' // Get the 0-based range of all the text
   DIM pCRange2 AS CTextRange2 = pCTextDoc.Range2(0, numChars)
   ' // Get the text
   DIM dwsText AS DWSTRING = pCRange2.GetText2(0)
   ' // The CTextDocument2 class and the CTextRange2 class will be destroyed when the scope ends
END SCOPE

To use with the pointer syntax.

' // Create a new instance of the CTextDocument2 class
DIM pCTextDocument2 AS CTextDocument2 PTR = NEW CTextDocument2(hRichEdit)
' // Get the number of characters of the text in the Rich Edit control
DIM numChars AS LONG = RichEdit_GetTextLength(hRichEdit)
' // Get the 0-based range of all the text
DIM pCRange2 AS CTextRange2 = pCTextDoc->Range2(0, numChars)
' // Get the text
DIM dwsText AS DWSTRING = pCRange2->GetText2(0)
' // Delete the range
Delete pCRange2
' // Delete the class
Delete pCTextDocument2

DESTRUCTOR

Called automatically when a class variable goes out of scope or is destroyed.

DESTRUCTOR CTextDocument2

LET

Assignment operator. The assigned pointer must be an “addrefed” one.

OPERATOR LET (BYVAL pTextDocument2 AS ITextDocument2 PTR)

CAST

Cast operator.

OPERATOR CAST () AS ITextDocument2 PTR

TextDocumentPtr

Returns a pointer to the underlying ITextDocument2 interface

FUNCTION TextDocumentPtr () AS ITextDocument2 PTR

Attach

Attaches an ITextDocument2 interface pointer to the class.

FUNCTION Attach (BYVAL pTextDocument2 AS ITextDocument2 PTR, _
   BYVAL fAddRef AS BOOLEAN = FALSE) AS HRESULT
Parameter Description
pTextDocument2 The ITextDocument2 interface pointer to attach.
fAddRef TRUE to increment the reference count of the object. Default is FALSE.

Detach

Detaches the underlying ITextDocument2 interface pointer from the class

FUNCTION Detach () AS ITextDocument2 PTR

GetLastResult

Returns the last result code

FUNCTION GetLastResult () AS HRESULT

SetResult

Sets the last result code.

FUNCTION SetResult (BYVAL Result AS HRESULT) AS HRESULT
Parameter Description
Result The HRESULT error code returned by the methods.

GetErrorInfo

Returns a description of the last result code.

PRIVATE FUNCTION GetErrorInfo (BYVAL nError AS LONG = -1) AS DWSTRING

GetName

Gets the file name of this document. This is the ITextDocument default property.

FUNCTION GetName () AS DWSTRING

Return value

The filename of this document, or an empty string if there is not a filename associated with this object.

Result code

If the method succeeds, GetLastResult returns S_OK. If the method fails, it returns one of the following COM error codes.

Result code Description
S_FALSE No file name associated with this object.
E_INVALIDARG Invalid argument.
E_OUTOFMEMORY Insufficient memory for output string.

GetSelection

Gets the active selection.

FUNCTION GetSelection () AS ITextSelection PTR

Return value

The ITextSelection pointer of the active selection.

Result code

If the method succeeds, GetLastResult returns S_OK. If the method fails, it returns one of the following COM error codes.

Result code Description
S_FALSE Indicates no active selection.
E_INVALIDARG Invalid argument.

GetStoryCount

Gets the count of stories in this document.

FUNCTION GetStoryCount () AS LONG

Return value

The number of stories in the document.

Result code

If the method succeeds, GetLastResult returns S_OK. If the method fails, it returns one of the following COM error codes.

Result code Description
E_INVALIDARG Invalid argument.

GetStoryRanges

Gets the story collection object used to enumerate the stories in a document.

FUNCTION GetStoryRanges () AS ITextStoryRanges PTR

Return value

A pointer to the ITextStoryRanges interface.

Result code

If the method succeeds, GetLastResult returns S_OK. If the method fails, it returns one of the following COM error codes.

Result code Description
E_NOTIMPL Not implemented; only one story in this document.

Remarks

Invoke this method only if GetStoryCount returns a value greater than 1.

GetSaved

Gets a value that indicates whether changes have been made since the file was last saved.

FUNCTION GetSaved () AS LONG

Return value

The value tomTrue if no changes have been made since the file was last saved, or the value tomFalse if there are unsaved changes.

Result code

If the method succeeds, GetLastResult returns S_OK. If the method fails, it returns one of the following COM error codes.

Result code Description
E_INVALIDARG Invalid argument.

SetSaved

Sets the document Saved property.

FUNCTION SetSaved (BYVAL Value AS LONG) AS HRESULT
Parameter Description
Value New value of the Saved property. It can be one of the following values:
tomTrue. No changes to the file since the last time it was saved.
tomFalse. There are changes to the file.

Return value

The return value is S_OK.

GetDefaultTabStop

Gets the default tab width.

FUNCTION GetDefaultTabStop () AS SINGLE

Return value

The default tab width.

Result code

If the method succeeds, GetLastResult returns S_OK. If the method fails, it returns one of the following COM error codes.

Result code Description
E_INVALIDARG Invalid argument.

SetDefaultTabStop

Sets the default tab stop, which is used when no tab exists beyond the current display position.

FUNCTION SetDefaultTabStop (BYVAL Value AS SINGLE = 36.0) AS HRESULT
Parameter Description
Value New default tab setting, in floating-point points. Default value is 36.0 points, that is, 0.5 inches.

If the method succeeds it returns S_OK. If the method fails, it returns one of the following COM error codes. For more information on COM error codes, see Error Handling in COM.

Result code

If the method succeeds, GetLastResult returns S_OK. If the method fails, it returns one of the following COM error codes.

Result code Description
E_INVALIDARG Invalid argument.
E_OUTOFMEMORY Insufficient memory.

New_

Opens a new document.

FUNCTION New_ () AS HRESULT

Return value

If the method succeeds, it returns S_OK.

Remarks

If another document is open, this method saves any current changes and closes the current document before opening a new one.

Open

Opens a specified document. There are parameters to specify access and sharing privileges, creation and conversion of the file, as well as the code page for the file.

FUNCTION Open (BYVAL pVar AS VARIANT PTR, BYVAL Flags AS LONG = 0, BYVAL CodePage AS LONG = 0) AS HRESULT
Parameter Description
pVar A VARIANT that specifies the name of the file to open.
Flags tomRTF: Open as RTF. tomText: Open as text ANSI or Unicode.
CodePage The code page to use for the file. Zero (the default value) means CP_ACP (ANSI code page) unless the file begins with a Unicode BOM 0xfeff, in which case the file is considered to be Unicode. Note that code page 1200 is Unicode, CP_UTF8 is UTF-8.

Return value

The return value can be an HRESULT value that corresponds to a system error or COM error code, including one of the following values.

Result code Description
S_OK Method succeeds.
E_INVALIDARG Invalid argument.
E_OUTOFMEMORY Insufficient memory.
E_NOTIMPL Feature not implemented.

Save

Saves the document.

FUNCTION Save (BYVAL pVar AS VARIANT PTR, BYVAL Flags AS LONG, BYVAL CodePage AS LONG) AS HRESULT
Parameter Description
pVar The save target. This parameter is a VARIANT, which can be a file name, or NULL.
Flags File creation, open, share, and conversion flags. For a list of possible values, see Open.
CodePage The specified code page. Common values are CP_ACP (zero: system ANSI code page), 1200 (Unicode), and 1208 (UTF-8).

Return value

The return value can be an HRESULT value that corresponds to a system error or COM error code, including one of the following values.

Result code Description
S_OK Method succeeds.
E_INVALIDARG Invalid argument.
E_OUTOFMEMORY Insufficient memory.
E_NOTIMPL Feature not implemented.

Remarks

To use the parameters that were specified for opening the file, use zero values for the parameters.

If pVar is null or missing, the file name given by this document’s name is used. If both of these are missing or null, the method fails.

If pVar specifies a file name, that name should replace the current Name property. Similarly, the Flags and CodePage arguments can overrule those supplied in the Open method and define the values to use for files created with the New_ method.

Unicode plain-text files should be saved with the Unicode byte-order mark (0xFEFF) as the first character. This character should be removed when the file is read in; that is, it is only used for import/export to identify the plain text as Unicode and to identify the byte order of that text. Microsoft Notepad adopted this convention, which is now recommended by the Unicode standard.

Freeze

Increments the freeze count.

FUNCTION Freeze () AS LONG

Return value

The updated freeze count.

Result code

If the count is nonzero, GetLastResult returns S_OK. If the count is zero, it returns FALSE.

Remarks

If the freeze count is nonzero, screen updating is disabled. This allows a sequence of editing operations to be performed without the performance loss and flicker of screen updating. To decrement the freeze count, call the Unfreeze method.

Unfreeze

Decrements the freeze count.

FUNCTION Unfreeze () AS LONG

Return value

The updated freeze count.

Result code

If the freeze count is zero, GetLastResult returns S_OK. If the method fails, it returns S_FALSE, indicating that the freeze count is nonzero.

Remarks

If the freeze count goes to zero, screen updating is enabled. This method cannot decrement the count below zero, and no error occurs if it is executed with a zero freeze count.

Note, if edit collection is active, screen updating is suppressed, even if the freeze count is zero.

BeginEditCollection

Turns on edit collection (also called undo grouping).

FUNCTION BeginEditCollection () AS HRESULT

Return value

If the method succeeds, it returns S_OK. If the method fails, it returns one of the following COM error codes.

Return code Description
S_OK Method succeeds.
S_FALSE Undo is not enabled.
E_NOTIMPL Feature not implemented.

Remarks

A single Undo command undoes all changes made while edit collection is turned on.

EndEditCollection

Turns off edit collection (also called undo grouping).

FUNCTION EndEditCollection () AS HRESULT

Return value

If the method succeeds, it returns S_OK. If the method fails, it returns a COM error code.

Return value Description
S_OK Method succeeds.
E_NOTIMPL Feature not implemented.

Remarks

The screen is unfrozen unless the freeze count is nonzero.

Undo

Performs a specified number of undo operations.

FUNCTION Undo (BYVAL Count AS LONG) AS LONG
Parameter Description
Count The specified number of undo operations. If the value of this parameter is tomFalse, undo processing is suspended. If this parameter is tomTrue, undo processing is restored.

Return value

The actual count of undo operations performed.

Result code

If all of the Count undo operations were performed, GetLastResult returns S_OK. If the method fails, it returns S_FALSE, indicating that less than Count undo operations were performed.

Redo

Performs a specified number of redo operations.

FUNCTION Redo (BYVAL Count AS LONG) AS LONG
Parameter Description
Count The number of redo operations specified.

Return value

The actual count of redo operations performed.

Result code

If the method succeeds GetLastResult returns S_OK. If the method fails, it returns the following COM error code.

Result code Description
S_OK Method succeeds.
S_FALSE Less than Count redo operations were performed.

Range

Retrieves a text range object for a specified range of content in the active story of the document.

FUNCTION Range (BYVAL cpActive AS LONG = 0, BYVAL cpAnchor AS LONG = 0) AS ITextRange PTR
Parameter Description
cpActive The start position of new range. The default value is zero, which represents the start of the document.
cpAnchor The end position of new range. The default value is zero.

Return value

Pointer to a ITextRange interface to the specified text range.

RangeFromPoint

Retrieves a range for the content at or nearest to the specified point on the screen.

FUNCTION RangeFromPoint (BYVAL x AS LONG, BYVAL y AS LONG) AS ITextRange PTR
Parameter Description
x The horizontal coordinate of the specified point, in screen coordinates.
y The vertical coordinate of the specified point, in screen coordinates.

Return value

Pointer to a ITextRange interface that corresponds to the specified point.

Result code

If the method succeeds GetLastResult returns S_OK. If the method fails, it returns the following COM error code.

Result code Description
S_OK Method succeeds.
E_INVALIDARG Invalid argument.
E_OUTOFMEMORY Insufficient memory.

GetCaretType

Gets the caret type.

FUNCTION GetCaretType () AS LONG

Return value

The caret type. It can be one of the following values:

Constant Value Description
tomKoreanBlockCaret &h1 The Korean block caret.
tomNormalCaret 0 Normal caret.
tomNullCaret &h2 NULL caret (caret suppressed)

Result code

If the method succeeds GetLastResult returns S_OK. If the method fails, it returns an HRESULT error code.

SetCaretType

Sets the caret type.

FUNCTION SetCaretType (BYVAL Value AS LONG) AS HRESULT
Parameter Description
Value The new caret type. It can be one of the following values:
Constant Value Description
tomKoreanBlockCaret &h1 The Korean block caret.
tomNormalCaret 0 Normal caret.
tomNullCaret &h2 NULL caret (caret suppressed)

Result code

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

GetDisplays

Gets the displays collection for this Text Object Model (TOM) engine instance.

FUNCTION GetDisplays () AS ITextDisplays PTR

Return value

A pointer to the ITextDisplays interface.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

Remarks

The rich edit control doesn’t implement this method.

GetDocumentFont

Gets an object that provides the default character format information for this instance of the Text Object Model (TOM) engine.

FUNCTION GetDocumentFont () AS ITextFont2 PTR

Return value

A pointer to the ITextFont2 interface.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

SetDocumentFont

Sets the default character formatting for this instance of the Text Object Model (TOM) engine.

FUNCTION SetDocumentFont (BYVAL pFont AS ITextFont2 PTR) AS HRESULT
Parameter Description
pFont The font object that provides the default character formatting.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

Remarks

You can also set the default character formatting by calling the Reset method of the ITextFont interface with a value of tomDefault.

GetDocumentPara

Gets an object that provides the default paragraph format information for this instance of the Text Object Model (TOM) engine.

FUNCTION GetDocumentPara () AS ITextPara2 PTR

Return value

A pointer to the ITextPara2 interface.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

SetDocumentPara

Sets the default paragraph formatting for this instance of the Text Object Model (TOM) engine.

FUNCTION SetDocumentPara (BYVAL pPara AS ITextPara2 PTR) AS HRESULT
Parameter Description
pPara The paragraph object that provides the default paragraph formatting.

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

Remarks

You can also set the default character formatting by calling the Reset method of the ITextFont interface with a value of tomDefault.

GetEastAsianFlags

Gets an object that provides the default paragraph format information for this instance of the Text Object Model (TOM) engine.

FUNCTION GetEastAsianFlags () AS LONG

Return value

The East Asian flags. This parameter can be a combination of the following values.

Value Meaning
tomRE10Mode TOM version 1.0 emulation mode.
tomUseAtFont Use @ fonts for CJK vertical text.
tomTextFlowMask A mask for the following four text orientations.
tomTextFlowES Ordinary left-to-right horizontal text.
tomTextFlowSW Ordinary East Asian vertical text.
tomTextFlowWN An alternative orientation.
tomTextFlowNE An alternative orientation.
tomUsePassword Use password control.
tomNoIME Turn off IME operation (see ES_NOIME).
tomSelfIME The rich edit host handles IME operation (see ES_SELFIME) .

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

GetGenerator

Gets the name of the Text Object Model (TOM) engine.

FUNCTION GetGenerator () AS DWSTRING

Return value

The name of the TOM engine.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

SetIMEInProgress

Sets the state of the Input Method Editor (IME) in-progress flag.

FUNCTION SetIMEInProgress (BYVAL Value AS LONG) AS HRESULT
Parameter Description
Value Use tomTrue to turn on the IME in-progress flag, or tomFalse to turn it off.

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

GetNotificationMode

Gets the notification mode.

FUNCTION GetNotificationMode () AS LONG

Return value

The notification mode. This parameter is set to tomTrue if notifications are active, or tomFalse if not.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

SetNotificationMode

Sets the notification mode.

FUNCTION SetNotificationMode (BYVAL Value AS LONG) AS HRESULT
Parameter Description
Value The notification mode. Use tomTrue to turn on notifications, or tomFalse to turn them off.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

GetSelection2

Gets the active selection.

FUNCTION GetSelection2 () AS ITextSelection2 PTR

Return value

A pointer to the ITextSelection2 interface of the selection. This pointer is NULL if the rich edit control is not in-place active.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

GetStoryRanges2

Gets an object for enumerating the stories in a document.

FUNCTION GetStoryRanges2 () AS ITextStoryRanges2 PTR

Return value

A pointer to the ITextStoryRanges2 interface used for enumerating stories.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

Remarks

Call this method only if the GetStoryCount method returns a value that is greater than one.

GetTypographyOptions

Gets the typography options.

FUNCTION GetTypographyOptions () AS LONG

Return value

A combination of the following typography options.

Value Meaning
TO_ADVANCEDTYPOGRAPHY Advanced typography (special line breaking and line formatting) is turned on.
TO_SIMPLELINEBREAK Normal line breaking and formatting is used.

Return value

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

GetVersion

Gets the version number of the Text Object Model (TOM) engine.

FUNCTION GetVersion () AS LONG

Return value

The version number. Byte 3 gives the major version number, byte 2 the minor version number, and the low-order 16 bits give the build number.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

GetWindow

Gets the handle of the window that the Text Object Model (TOM) engine is using to display output.

FUNCTION GetWindow () AS __int64

Return value

The handle of the window that the TOM engine is using.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

Remarks

A rich edit control doesn’t need to own the window that the TOM engine is using. For example, the rich edit control might be windowless.

The Input Method Editor (IME) needs the handle of the window that is receiving keyboard messages. This method retrieves that handle.

AttachMsgFilter

Attaches a new message filter to the edit instance. All window messages that the edit instance receives are forwarded to the message filter.

FUNCTION AttachMsgFilter (BYVAL pFilter AS IUnknown PTR) AS HRESULT
Parameter Description
pFilter The message filter.

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

Remarks

The message filter must be bound to the document before it can be used.

CheckTextLimit

Checks whether the number of characters to be added would exceed the maximum text limit.

FUNCTION CheckTextLimit (BYVAL cch AS LONG) AS LONG
Parameter Description
cch The number of characters to be added.

Return value

The number of characters that exceed the maximum text limit. This parameter is 0 if the number of characters does not exceed the limit.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

GetCallManager

Gets the call manager.

FUNCTION GetCallManager () AS IUnknown PTR

Return value

The call manager object.

Result code

If the method succeeds,GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

Remarks

The call manager object is opaque to the caller. The Text Object Model (TOM) engine uses the object to handle internal notifications for particular scenarios.

GetClientRect

Retrieves the client rectangle of the rich edit control.

FUNCTION GetClientRect (BYVAL nType AS LONG, BYVAL pLeft AS LONG PTR, _
   BYVAL pTop AS LONG PTR, BYVAL pRight AS LONG PTR, BYVAL pBottom AS LONG PTR) AS HRESULT
Parameter Description
nType The client rectangle retrieval options. It can be a combination of the following values.
tomClientCoord. Retrieve the rectangle in client coordinates. If this value isn’t specified, the function retrieves screen coordinates.
tomIncludeInset. Add left and top insets to the left and top coordinates of the client rectangle, and subtract right and bottom insets from the right and bottom coordinates.
tomTransform. Use a world transform (XFORM) provided by the host application to transform the retrieved rectangle coordinates.
pLeft The x-coordinate of the upper-left corner of the rectangle.
pTop The y-coordinate of the upper-left corner of the rectangle.
pRight The x-coordinate of the lower-right corner of the rectangle.
pBottom The y-coordinate of the lower-right corner of the rectangle.

Return value

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

GetEffectColor

Retrieves the color used for special text attributes.

FUNCTION GetEffectColor (BYVAL Index AS LONG) AS ULONG
Parameter Description
Index The index of the color to retrieve. It can be one of the following values.
Index Meaning
0 Text color.
1 RGB(0, 0, 0)
2 RGB(0, 0, 255)
3 RGB(0, 255, 255)
4 RGB(0, 255, 0)
5 RGB(255, 0, 255)
6 RGB(255, 0, 0)
7 RGB(255, 255, 0)
8 RGB(255, 255, 255)
9 RGB(0, 0, 128)
10 RGB(0, 128, 128)
11 RGB(0, 128, 0)
12 RGB(128, 0, 128)
13 RGB(128, 0, 0)
14 RGB(128, 128, 0)
15 RGB(128, 128, 128)
16 RGB(192, 192, 192)

Return value

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

Remarks

The first 16 index values are for special underline colors. If an index between 1 and 16 hasn’t been defined by a call to the GetEffectColor method, GetEffectColor returns the corresponding Microsoft Word default color.

GetPreferredFont

Retrieves the preferred font for a particular character repertoire and character position.

FUNCTION GetPreferredFont (BYVAL cp AS LONG, BYVAL CodePage AS LONG, _
   BYVAL Options AS LONG, BYVAL curCodepage AS LONG, BYVAL curFontSize AS LONG, BYREF dwsFontName AS DWSTRING, _
   BYVAL pPitchAndFamily AS LONG PTR, BYVAL pNewFontSize AS LONG PTR) AS HRESULT
Parameter Description
cp The character position for the preferred font.
CharRep The character repertoire index for the preferred font. It can be one of the following values: tomAboriginal, tomAnsi, tomArabic, tomArmenian, tomBaltic, tomBengali, tomBIG5, tomBraille, tomCherokee, tomCyrillic, tomDefaultCharRep, tomDevanagari, tomEastEurope, tomEmoji, tomEthiopic, tomGB2312, tomGeorgian, tomGreek, tomGujarati, tomGurmukhi, tomHangul, tomHebrew, tomJamo, tomKannada, tomKayahli, tomKharoshthi, tomKhmer, tomLao, tomLimbu, tomMac, tomMalayalam, tomMongolian, tomMyanmar, tomNewTaiLu, tomOEM, tomOgham, tomOriya, tomPC437, tomRunic, tomShiftJIS, tomSinhala, tomSylotinagr, tomSymbol, tomSyriac, tomTaiLe, tomTamil, tomTelugu, tomThaana, tomThai, tomTibetan, tomTurkish, tomUsymbol, tomVietnamese, tomYi.
Options The preferred font options. The low-order word can be a combination of the following values.
tomIgnoreCurrentFont, tomMatchCharRep, tomMatchFontSignature, tomMatchAscii, tomGetHeightOnly, tomMatchMathFont. If the high-order word of Options is tomUseTwips, the font heights are given in twips.
curCharRep The index of the current character repertoire.
curFontSize The current font size.
dwsFontName [OUT] The font name.
pPitchAndFamily [OUT] The font pitch and family.
pNewFontSize [OUT] The new font size.

Return value

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

GetImmContext

Gets the Input Method Manager (IMM) input context from the Text Object Model (TOM) host.

FUNCTION GetImmContext () AS __int64

Return value

The IMM input context.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

GetProperty

Retrieves the value of a property.

FUNCTION GetProperty (BYVAL nType AS LONG) AS LONG
Parameter Description
nType The identifier of the property to retrieve. It can be one of the following property IDs: tomCanCopy, tomCanRedo, tomCanUndo, tomDocMathBuild, tomMathInterSpace, tomMathIntraSpace, tomMathLMargin, tomMathPostSpace, tomMathPreSpace, tomMathRMargin, tomMathWrapIndent, tomMathWrapRight, tomUndoLimit, tomEllipsisMode, tomEllipsisState

Return value

The value of the property.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

GetStrings

Gets a collection of rich-text strings.

FUNCTION GetStrings () AS ITextStrings PTR

Return value

A pointer to the ITextStrings interface of the collection of rich-text strings.

Notify

Notifies the Text Object Model (TOM) engine client of particular Input Method Editor (IME) events.

FUNCTION Notify (BYVAL nNotify AS LONG) AS HRESULT
Parameter Description
nNotify An IME notification code.

Rerturn value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

Range2

Retrieves a new text range for the active story of the document.

FUNCTION Range2 (BYVAL cpActive AS LONG = 0, BYVAL cpAnchor AS LONG = 0) AS ITextRange2 PTR
Parameter Description
cpActive The active end of the new text range. The default value is 0; that is, the beginning of the story.
cpAnchor The anchor end of the new text range. The default value is 0.

Return value

The new text range.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

RangeFromPoint2

Retrieves the degenerate range at (or nearest to) a particular point on the screen.

FUNCTION RangeFromPoint2 (BYVAL x AS LONG, BYVAL y AS LONG, BYVAL nType AS LONG) AS ITextRange2 PTR
Parameter Description
x The x-coordinate of a point, in screen coordinates.
y The y-coordinate of a point, in screen coordinates.
nType The alignment type of the specified point. For a list of valid values, see the GetPoint method of the ITextRange interface.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESUL** error code.

ReleaseCallManager

Releases the call manager.

FUNCTION ReleaseCallManager (BYVAL pVoid AS IUnknown PTR) AS HRESULT
Parameter Description
pvoid The call manager object to release.

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

ReleaseImmContext

Releases an Input Method Manager (IMM) input context.

FUNCTION ReleaseImmContext (BYVAL Context AS __int64) AS HRESULT
Parameter Description
Context The IMM input context to release.

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

SetEffectColor

Specifies the color to use for special text attributes.

FUNCTION SetEffectColor (BYVAL Index AS LONG, BYVAL Value AS ULONG) AS HRESULT
Parameter Description
Index The index of the color to retrieve. For a list of values, see the table below.
Value The new color for the specified index.
Index Meaning
0 Text color.
1 RGB(0, 0, 0)
2 RGB(0, 0, 255)
3 RGB(0, 255, 255)
4 RGB(0, 255, 0)
5 RGB(255, 0, 255)
6 RGB(255, 0, 0)
7 RGB(255, 255, 0)
8 RGB(255, 255, 255)
9 RGB(0, 0, 128)
10 RGB(0, 128, 128)
11 RGB(0, 128, 0)
12 RGB(128, 0, 128)
13 RGB(128, 0, 0)
14 RGB(128, 128, 0)
15 RGB(128, 128, 128)
16 RGB(192, 192, 192)

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

Remarks

The first 16 index values are for special underline colors. If an index between 1 and 16 hasn’t been defined by a call to the SetEffectColor method of the ITextDocument2 interface, the corresponding Microsoft Word default color is used.

SetProperty

Specifies a new value for a property.

FUNCTION SetProperty (BYVAL nType AS LONG, BYVAL Value AS LONG) AS HRESULT
Parameter Description
nType The identifier of the property. It can be one of the following property IDs: tomCanCopy, tomCanRedo, tomCanUndo, tomDocMathBuild, tomMathInterSpace, tomMathIntraSpace, tomMathLMargin, tomMathPostSpace, tomMathPreSpace, tomMathRMargin, tomMathWrapIndent, tomMathWrapRight, tomUndoLimit, tomEllipsisMode, tomEllipsisState.
Value The new property value.

Return value

If the method succeeds, it returns NOERRO. Otherwise, it returns an HRESULT error code.

SetTypographyOptions

Specifies the typography options for the document.

FUNCTION SetTypographyOptions (BYVAL Options AS LONG, BYVAL Mask AS LONG) AS HRESULT
Parameter Description
Options The typography options to set. For a list of possible options, see the table below.
Mask A mask identifying the options to set. For example, to turn on TO_ADVANCEDTYPOGRAPHY, call SetTypographyOptions (TO_ADVANCEDTYPOGRAPHY, TO_ADVANCEDTYPOGRAPHY).

Typography options.

Value Meaning
TO_ADVANCEDTYPOGRAPHY Advanced typography (special line breaking and line formatting) is turned on.
TO_SIMPLELINEBREAK Normal line breaking and formatting is used.

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

SysBeep

Generates a system beep.

FUNCTION SysBeep () AS HRESULT

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

Update

Updates the selection and caret.

FUNCTION Update (BYVAL Value AS LONG) AS HRESULT
Parameter Description
Value Scroll flag. Use tomTrue to scroll the caret into view.

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

UpdateWindow

Notifies the client that the view has changed and the client should update the view if the Text Object Model (TOM) engine is in-place active.

FUNCTION UpdateWindow () AS HRESULT

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

GetMathProperties

Gets the math properties for the document.

FUNCTION GetMathProperties () AS LONG

Return value

A combination of the following math properties:

Property Meaning
tomMathDispAlignMask Display-mode alignment mask.
tomMathDispAlignCenter Center (default) alignment.
tomMathDispAlignLeft Left alignment.
tomMathDispAlignRight Right alignment.
tomMathDispIntUnderOver Display-mode integral limits location.
tomMathDispFracTeX Display-mode nested fraction script size.
tomMathDispNaryGrow Math-paragraph n-ary grow.
tomMathDocEmptyArgMask Empty arguments display mask.
tomMathDocEmptyArgAuto Automatically use a dotted square to denote empty arguments, if necessary.
tomMathDocEmptyArgAlways Always use a dotted square to denote empty arguments.
tomMathDocEmptyArgNever Don’t denote empty arguments.
tomMathDocSbSpOpUnchanged Display the underscore (_) and caret (^) as themselves.
tomMathDocDiffMask Style mask for the tomMathDocDiffUpright, tomMathDocDiffItalic, tomMathDocDiffOpenItalic options.
tomMathDocDiffItalic Use italic (default) for math differentials.
tomMathDocDiffUpright Use an upright font for math differentials.
tomMathDocDiffOpenItalic Use open italic (default) for math differentials.
tomMathDispNarySubSup Math-paragraph non-integral n-ary limits location.
tomMathDispDef Math-paragraph spacing defaults.
tomMathEnableRtl Enable right-to-left (RTL) math zones in RTL paragraphs.
tomMathBrkBinMask Equation line break mask.
tomMathBrkBinBefore Break before binary/relational operator.
tomMathBrkBinAfter Break after binary/relational operator.
tomMathBrkBinDup Duplicate binary/relational before/after.
tomMathBrkBinSubMask Duplicate mask for minus operator.
tomMathBrkBinSubMM - - (minus on both lines).
tomMathBrkBinSubPM + -
tomMathBrkBinSubMP - +

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

SetMathProperties

Sets the math properties for the document.

FUNCTION SetMathProperties (BYVAL Options AS LONG, BYVAL Mask AS LONG) AS HRESULT
Parameter Description
Options The math properties to set. For a list of possible properties, see the table below.
Mask The math mask. For a list of possible masks, see the table below.
Property Meaning
tomMathDispAlignMask Display-mode alignment mask.
tomMathDispAlignCenter Center (default) alignment.
tomMathDispAlignLeft Left alignment.
tomMathDispAlignRight Right alignment.
tomMathDispIntUnderOver Display-mode integral limits location.
tomMathDispFracTeX Display-mode nested fraction script size.
tomMathDispNaryGrow Math-paragraph n-ary grow.
tomMathDocEmptyArgMask Empty arguments display mask.
tomMathDocEmptyArgAuto Automatically use a dotted square to denote empty arguments, if necessary.
tomMathDocEmptyArgAlways Always use a dotted square to denote empty arguments.
tomMathDocEmptyArgNever Don’t denote empty arguments.
tomMathDocSbSpOpUnchanged Display the underscore (_) and caret (^) as themselves.
tomMathDocDiffMask Style mask for the tomMathDocDiffUpright, tomMathDocDiffItalic, tomMathDocDiffOpenItalic options.
tomMathDocDiffItalic Use italic (default) for math differentials.
tomMathDocDiffUpright Use an upright font for math differentials.
tomMathDocDiffOpenItalic Use open italic (default) for math differentials.
tomMathDispNarySubSup Math-paragraph non-integral n-ary limits location.
tomMathDispDef Math-paragraph spacing defaults.
tomMathEnableRtl Enable right-to-left (RTL) math zones in RTL paragraphs.
tomMathBrkBinMask Equation line break mask.
tomMathBrkBinBefore Break before binary/relational operator.
tomMathBrkBinAfter Break after binary/relational operator.
tomMathBrkBinDup Duplicate binary/relational before/after.
tomMathBrkBinSubMask Duplicate mask for minus operator.
tomMathBrkBinSubMM - - (minus on both lines).
tomMathBrkBinSubPM + -
tomMathBrkBinSubMP - +

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

GetActiveStory

Gets the active story; that is, the story that receives keyboard and mouse input.

FUNCTION GetActiveStory () AS ITextStory PTR

Return value

A pointer to the ITextStory interface of the active story.

Result code

If the method succeeds, GetLastResult returns NOERROR. Otherwise, it returns an HRESULT error code.

SetActiveStory

Sets the active story; that is, the story that receives keyboard and mouse input.

FUNCTION SetActiveStory (BYVAL pStory AS ITextStory PTR) AS HRESULT
Parameter Description
pStory The story to set as active.

Return value

If the method succeeds, it returns NOERROR. Otherwise, it returns an HRESULT error code.

GetMainStory

Gets the main story.

FUNCTION GetMainStory () AS ITextStory PTR

Return value

A pointer to the ITextStory interface of the main story.

Result code

If this method succeeds, GetLastResult returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

A rich edit control automatically includes the main story; a call to the GetNewStory method is not required.

GetNewStory

Gets a new story. Not implemented.

FUNCTION GetNewStory () AS ITextStory PTR

Return value

A pointer to the ITextStory interface of the new story.

Result code

If this method succeeds, GetLastResult returns S_OK. Otherwise, it returns an HRESULT error code.

GetStory

Retrieves the story that corresponds to a particular index.

FUNCTION GetStory (BYVAl Index AS LONG) AS ITextStory PTR
Parameter Description
Index The index of the story to retrieve.

Return value

A pointer to the ITextStory interface of the requested story.

Result code

If this method succeeds, GetLastResult returns S_OK. Otherwise, it returns an HRESULT error code.